NavChooseFile

NavChooseFile
Header:	Navigation.h		Carbon status:	Supported

Creates a simple dialog box that prompts the user to select a file.

OSErr NavChooseFile (
    AEDesc *defaultLocation, 
    NavReplyRecord *reply, 
    NavDialogOptions *dialogOptions, 
    NavEventUPP eventProc, 
    NavPreviewUPP previewProc, 
    NavObjectFilterUPP filterProc, 
    NavTypeListHandle typeList, 
    void *callBackUD
);

defaultLocation: A pointer to an Apple event descriptor structure (AEDesc). Before calling NavChooseFile, you can set up a structure of AEDesc type 'typeFSS' to specify a default location to be viewed. If you pass NULL in this parameter, Navigation Services displays the last location visited during a call to the NavChooseFile function. If the file system specification in the AEDesc structure does not describe a directory or volume, Navigation Services uses the desktop as the default location.
reply: A pointer to a structure of type NavReplyRecord. Upon return, Navigation Services uses this structure to provide data to your application about the results of your NavChooseFile call.
dialogOptions: A pointer to a structure of type NavDialogOptions. Before calling NavChooseFile, you can set up this structure to specify dialog box settings. If you pass NULL in this parameter, Navigation Services uses the defaults for all options. See “Dialog Option Configuration Constants” for a description of the default settings.
eventProc: A Universal Procedure Pointer (UPP) of type NavEventProcPtr that points to your application-defined event-handling function. You obtain this UPP by calling the macro NewNavEventProc. Implementing an event-handling function allows your application to update windows after the user moves or resizes the dialog box. If you pass NULL in this parameter, the Choose a File dialog box is not movable or resizable. For more information, see “Handling Events”.
previewProc: A Universal Procedure Pointer (UPP) of type NavPreviewProcPtr that points to your application-defined preview function. Obtain this UPP by calling the macro NewNavPreviewProc. A preview function allows your application to draw previews or to override Navigation Services previews. For more information, see “Drawing Custom Previews”.
filterProc: A Universal Procedure Pointer (UPP) of type NavObjectFilterProcPtr that points to your application-defined filter function. Obtain this UPP by calling the macro NewNavObjectFilterProc. An application-defined filter function determines if a volume, directory, or file should be displayed in the browser list or pop-up menus. For more information, see “Filtering File Objects”.
typeList: A handle to a structure of type NavTypeList. Before calling NavChooseFile, you can set up this structure to declare file types that your application can open. For more information, see “Providing File Opening Options”.
callBackUD: A pointer to a value set by your application. When the NavChooseFile function calls your event-handling function, the callBackUD value is passed back to your application.

function result: A result code.

DISCUSSION

This function allows the user to choose a single file, such as a preferences file, for an action other than opening. The NavChooseFile function is similar to NavGetFile, but is limited to selecting a single file.

The dialog box displayed by the NavChooseFile function does not display a Show menu. If you wish to control the files displayed by the browser list or the pop-up menus, you must specify a list of file types in the typeList parameter or specify a filter function in the filterProc parameter. If you specify a list of file types in the typeList parameter, the NavChooseFile function ignores the signature field of the NavTypeList structure. This means that all files of the types specified in the list of file types will be displayed, regardless of their application signature. For more information, see “Filtering File Objects”.

SPECIAL CONSIDERATIONS

The dialog box displayed by the NavChooseFile function does not display a Show menu. If you wish to control the files displayed by the browser list or the pop-up menus, you must specify a list of file types in the typeList parameter or specify a filter function in the filterProc parameter. If you specify a list of file types in the typeList parameter, the NavChooseFile function ignores the signature field of the NavTypeList structure. This means that all files of the types specified in the list of file types will be displayed, regardless of their application signature.

VERSION NOTES

Available in Navigation Services 1.0 and later.

AVAILABILITY

Supported in Carbon. Available in CarbonLib 1.0 and later when NavigationLib 1.0 or later is installed. Exported by CarbonLib 1.0 and later and by NavigationLib 1.0 and later.